This article contains answers to the most frequently asked questions about the Remote API.

Are there any limitations on API usage?

Global limitations are described in the documentation. Typically, reaching these limitations indicates that the developed application is not optimized for working with the API. For example, it makes multiple authorization requests instead of maintaining one active session.

There are also limitations on some requests, which are mentioned in the request description in the documentation. For example, only one report can be executed during a session at a time. If the session contains the results of the previous report execution, they should be deleted using the request report/cleanup_result before executing the next report. Additionally, the request to execute reports cannot be performed simultaneously with some other requests.

Is it possible to organize real-time data transfer from Wialon using the API?

No. API requests work on the request-response method. This means that data on the receiving side will not be updated without sending a request.

If it is necessary to receive data from hardware as soon as new messages arrive, retranslators can be used.

How to create a locator using the API?

Let's consider an example: it is necessary to create a locator with infinite lifespan, which will display units with system IDs 11111111 and 22222222, as well as geofences from a resource with system ID 12345678, but will not display units’ tracks.

To do this, you need to use the request token/update:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update&params=
{"callMode":"create","app":"locator","at":0,"dur":0,"fl":256,"p":"{\"note\":\"Bus\",\"zones\":1,\"tracks\":0}","items":[11111111,22222222,12345678]}&sid=SESSION_IDENTIFIER

The response to the request will include the parameter h containing the token value. To obtain the desired link, the token value should be inserted into the following link: https://hosting.wialon.com/locator/index.html?t=TOKEN_VALUE

How to obtain a token with maximum access and infinite lifespan?

If token creation is done through an extended form, it is necessary to use the parameters access_type=-1 and duration=0. For example:

https://hosting.wialon.com/login.html?client_id=APP_NAME&access_type=256&activation_time=0&duration=0&lang=en&flags=0&user=USER_NAME

If token creation is done through the request token/update, it is necessary to use the parameters fl=-1 and dur=0. For example:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update&params=
{"callMode":"create","app":"Wialon Hosting","at":0,"dur":0,"fl":-1,"p":"{}"}&sid=SESSION_IDENTIFIER

Why can an error with code 1 be returned when using an unlimited token?

An error with code 1 indicates that the current session is invalid. The token's lifespan is not directly related to the session.

To fix the situation, it is necessary to perform authorization again. The response to the token login contains the parameter eid, and its value is the unique session identifier. It will be used in almost all API requests.

How to fix an error with code 4?

An error with code 4 corresponds to invalid input, which can mean:

• incorrect data type (numeric, text, etc.);
  

• incorrect parameter names;
  
• incorrect separators (commas, quotes, spaces, brackets, etc.);
• absence of encoding for transmission in the URL.

Let's consider an example of a request with all the mentioned errors:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result&params={"format":"2";"compres":0;"outputFileName":"List of trips"}&sid=SESSION_IDENTIFIER

In this example, the following errors were made:

1. The parameter format should contain a number, but since its value is enclosed in quotes, it is interpreted as text.
   
2. Instead of the parameter with the name compress, a parameter with the name compres was used.
3. A semicolon was used instead of a comma to separate the parameters.
4. The space character was not encoded for transmission in the URL.

The correct request will look like this:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result&params={"format":2,"compress":0,"outputFileName":"List%20of%20trips"}&sid=SESSION_IDENTIFIER

Why does an error with code 7 occur when using unique unit IDs?

API requests use internal system IDs of items, not unique unit IDs from the General tab. By default, these IDs are not displayed in web interfaces.

You can use the search items by property request (core/search_items) to obtain the system IDs of items. The desired value will be found in the parameter id of the response to this request.

Why is access to the unit restricted even though the user has full access rights?

The problem is likely due to insufficient rights of the token being used.

To check the rights of the token, perform the token login:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login&params={"token":"TOKEN_VALUE"}

The response will contain the parameter fl, which displays the current rights of the token. To change them, edit the current token or create a new one.

How to get the last coordinates of units?

To obtain the last coordinates of multiple units, you can use the search items by property request (core/search_items). In this case, you need to specify access flags according to which the response will display unit names ("flag":1") and information about the last position of units ("flag":1024). Flags can be summed together, so the request will use the value 1 + 1024 = 1025.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1025,"from":0,"to":0}&sid=SESSION_IDENTIFIER

How to get a list of all units available to the user?

To display all units available to the user, you can use the search items by property request (core/search_items) with the value "propValueMask":"*".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

The response will return a list of units that are accessible to the user whose session identifier was used in the request.

How to get the names of groups to which a certain unit is added?

To get the names of groups that include a unit with the system ID 11112222, you need to use the search items by property request (core/search_items) with the values "itemsType":"avl_unit_group", "propName":"sys_units", and "propType":"list".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"sys_units","propValueMask":11112222,"sortType":"sys_name","propType":"list"},"force":1,"flags":1,"from":0,"to":0}}&sid=SESSION_IDENTIFIER

How to get the names of units from a certain group?

To get the names of units that are included in a group named Group, you need to use two search items by property requests (core/search_items): the first one will search for the unit group (avl_unit_group), and the second one will search for the unit (avl_unit).

1. First, you need to get a list of system IDs of units that belong to the group (specify its name in the parameter propValueMask):

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"sys_name","propValueMask":"Group","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

    Response

   {
   	"searchSpec":{
   		"itemsType":"avl_unit_group",
   		"propName":"sys_name",
   		"propValueMask":"Group",
   		"sortType":"sys_name",
   		"propType":"",
   		"or_logic":"0"
   	},
   	"dataFlags":1,
   	"totalItemsCount":1,
   	"indexFrom":0,
   	"indexTo":0,
   	"items":[
   		{
   			"nm":"Group",
   			"cls":5,
   			"id":10000000,
   			"mu":0,
   			"u":[
   				20000001,
   				20000002,
   				20000003
   			],
   			"uacl":-1
   		}
   	]
   }
   

2. In the response to the previous request, you need to find the parameter u with the system IDs of units. You should substitute them in the parameter propValueMask for the next search request:
   

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_id","propValueMask":"20000001,20000002,20000003","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

    Response

   {
   	searchSpec:{
   		itemsType:"avl_unit",
   		propName:"sys_id",
   		propValueMask:"20000001,20000002,20000003",
   		sortType:"sys_name",
   		propType:"",
   		or_logic:"0"
   	},
   	dataFlags:1,
   	totalItemsCount:3,
   	indexFrom:0,
   	indexTo:0,
   	items:[
   		{
   			nm:"Unit_1",
   			cls:2,
   			id:20000001,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_2",
   			cls:2,
   			id:20000002,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_3",
   			cls:2,
   			id:20000003,
   			mu:0,
   			uacl:-1
   		}
   	]
   }
   

   The names of units will be displayed in the parameters nm.

Why do the results of the report differ between the interface and the response to the API request?

When executing reports through API requests, it is important not to forget to set the time zone for the current session. To do this, immediately after authorization, you should apply the user's localization settings once.

Ekaterina Grib,Customer Service Engineer 2023-09-01